WiFiAdmin - A Web Interface For Wireless Tools
==============================================

Authors:
  Panousis Thanos <panousis@ceid.upatras.gr>
  Dimopoulos Eythimios <dimopule@ceid.upatras.gr>
ReAuthors:
  Vasilis <basos@users.sf.net>
  Korki <korki@users.sf.net>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 2 as
published by the Free Software Foundation. See COPYING for more
details.

Wifiadmin is a free php graphical interface to mainly hostap and wireless tools in
general. We are trying so that wifiadmin is as self-configuring and distribution
independent as possible.
Contact us by the mailing list (see http://wifiadmin.sf.net)


Prerequisites
=============

* WEB SERVER with PHP : An http server with PHP support must also be running. You will
  also need the command line interface(CLI) for php. If '$ which php' returns some path,
  CLI is present in your system.

  Wifiadmin can send emails, in order to confirm new accounts or remind user passwords
   You can disable this functionality ($C_send_emails conf variable)
  According to the php manual:
   For the Mail functions to be available, PHP must have access to the sendmail binary
   on your system during compile time. If you use another mail program, such as qmail
   or postfix, be sure to use the appropriate sendmail wrappers that come with them.
   PHP will first look for sendmail in your PATH, and then in the following:
   /usr/bin:/usr/sbin:/usr/etc:/etc:/usr/ucblib:/usr/lib. It's highly recommended to
   have sendmail available from your PATH. Also, the user that compiled PHP must have
   permission to access the sendmail binary.
  This usually means that if a normal user of your system is able to send emails, then
   wifiadmin can do that too.

*  A (supported) router. Currently a linux one.

*  (optional but strongly encouraged) Mysql Working Server : WiFiAdmin has a
  community section, that holds information about conected clients usind a
  mysql database. You can disable mysql usage ($C_use_mysql conf variable),
  which will disable the community section. Note that if you use mysql,
  usernames, passwords and user privileges will be saved  in the database.

* (optional) RRD-tool : A fairly recent version of RRD-tool must be installed on the system if
   you want offline graphics support. You can disable offline graphs ($C_gen_graphs conf var)


INSTALLATION [The New automated way ]
============

Grab the latest release from http://wifiadmin.sourceforge.net and procceed
with the followning steps:

1) Decompress in a directory reachable from your web server(htdocs),
  keeping in mind the directory structure.

2) Optional : If you need fully automated proccess you need to
  give write access to the webserver user, for the directory config

  For example, from wifiadmin root directory type (assuming apache runs
  as www-data - see FIND APACHE USER below)
  # chown www-data: ./config
  - or -
  # cd config ; touch routers.ini; chown www-data routers.ini ; touch config.php; chown www-data config.php
  If you prefer a safer setup don't grand write access. You will be promted
  to manualy copy the config  file to its place during the installation proccess.

3) Point you browser to your.domain/wifiadmin/ or your.ip/wifiadmin/
  If you miss the config.php the installation proccess will be initialized and you will
  be guided to the rest of the proccess.
  Be prepared that some parts of the installation concerning the routers registrarion
  are done via shell scripts. You will need :
    a) to know web server user for this (See FIND APACHE USER section bellow) as well as
    b) have shell access to the web server machine as the apache user (but MAY need
    root access if the apache user account is not setup correctrly) and finaly
    c) to know root password of the router machine(s).

4) OPTIONAL: If you want offline graphs to be created (network usage,AP users, Signal,etc)
  see step 5 at the manual installation instractions bellow.

 SECURITY NOTICE : Procceed to the installation proccess imediately after unpacking.
  At this early stage *anyone* who can view your webpage can perform the
  installation. After the proccess user accounds will be created and things
  will be more secure.

 SECURITY NOTICE: WIFIADMIN HAS A DEFAULT ADMIN PASSWORD. When finishing the installation
  change the admin password as soon as possible, by logging in as user 'admin' with
  password 'wifiadmin'. Go to user management, choose 'admin', and  type a different
  password. You can LOOSE complete network access to your box if you are careless enough...


UPGRADING
=========
- From 0.1 and on: Just uppack the new version and keep the files under config, graph,
   rrd_database dirs.
   Database update will me managed by the update proccess. Point to wifiadmin location
   and you will be prompted..   Configuration File / Database / Routers update can now
   be handled automatically by wifiadmin
- As of 0.1 create_graphs.php cron job is not neccessary.
- If you are installing a version greater than 0.0.3 change your sudo configuration.


  SECURITY NOTICE : Point your browser to the wifiadmin location imediately after update.
    It could be possible that unpriviledged users may perform actions.


FIND APACHE USER
================
 You can find out the user that apache runs with, by:
  #ps aux | grep http   or
  #ps aux | grep apache

Notice : it might show lots of apache proccesses and one of the running as root. This is the "father" apache
  proccess and  should be ignored
  e.g
 #ps uax | grep apache
root     17159  0.0  0.0  25632    84 ?        Ss   Jun15   0:16 /usr/sbin/apache2 -k start
www-data 17164  0.0  1.6  29244  8424 ?        S    Jun15   0:55 /usr/sbin/apache2 -k start
www-data 17165  0.0  1.8  30236  9412 ?        S    Jun15   0:28 /usr/sbin/apache2 -k start
www-data 17411  0.0  1.3  26108  6860 ?        S    Jun15   0:43 /usr/sbin/apache2 -k start

Or you should look for "User" directive in apache configuration file (e.g. /etc/apache2/apache2.conf)
  e.g.
  User www-data
  Group www-data


NOTES
=====

--- Users / Privileges
Wifiadmin supports users with different priviledges. You can create
different classes of users. A non-logged in user, defaults to the
'guest' user. You can change the amount of information guest and every
other user can access by assigning privileges. Most privileges
are self explaining. But here are some notes :


- "Edit Privileges" is synonym to the *admin* as he or she can change every
other privilege. Be aware to who you are giving edit_privileges. By design,
you cannot get locked out of the system by deleting the last user that has
an edit-privileges priviledge.


- "View status Ext" gives more view only capabilities. Right now it offers
real time graphs as someone could preform a denial of service by modifying
some values in the graph scripts (asking for tons of graph data).


-- Supported Drivers
At linux any wireless extentions enabled driver should be working fairly good.
But note that currently the known supported drivers for AP management are hostap
and madwifi. Also hostap is enjoying some special feautures with AP Access Control
as they are offered by this driver only.
If you have tested other drivers or want to contib AP specific code you can post
at the mailing list (see http://wifiadmin.sf.net)


-- Supported Systems
Wifiadmin intents to become multi pratform (mainly for other *X systems which miss linux
stuff like wireless extentions). Right now the abstaction API has been created for linux.
And this is the only supported platform.
If you have programming skills and would like to see your device supported you can contrib
code. Contact the developers with the mailing list (see http://wifiadmin.sf.net)


-- Locale independent
Wifiadmin intents to learn foreign languages. If you want you can contrib a full translation
of the language specific strings. All the content should be in one (big) file under lang directory.
You can base your translation on en_GB.php (which is the default locale).


-- Reboot persistent settings
Right now changes that are made to the device parameters are not saved in the system and thus
are lost on router reboot. Wifiadmin intents to change this behaivour at some point and
obtain some memmory. Contributions and ideas are welcome.


--- Banning MACs
You can ban a MAC, through the wireless status page.
You can unban MACs, view and alter Access Control policies in wireless
security page. Note that banning a MAC on an open-policy AP will result
in a deny policy.


--- Manual Configuration
Things can be manually configured in the config/config.php file. The
variables are marked by comments. Change them at your own risk. You can
also point your browser to your.domain/wifiadmin/install.php?mode=config
at any time. Instractions on how to change conf variables in a secure way
thru the graphical gui will guide you.


--- RRD
Wifiadmin makes use of round robin dbs, and we take for granted that you have a
recent version of rrd-tool. You can also disable graphs generation and to rrdtool
will be needed then.


Installation [ The Old Manual way]
============

Grab the latest release from http://sourceforge.net and procceed
with the followning steps:

1) Decompress in a directory reachable from your web server(htdocs),
  keeping in mind the directory structure.

2) If you disable mysql usage($C_use_mysql variable in the config/config.php
  file):

  Give write access to the user that you are running PHP, to the file
  config/passwd .For example, from wifiadmin root directory type
  'chown apache:/ config; chown apache:/ config/passwd', depending
  on your local configuration.

  If you enable mysql usage:

  Within the directory, you'll find a a file named "mysql.sql".
  Contained in this file are the SQL statements necessary to create the
  WiFiAdmin database. Log onto your database server under the root account (or
  other account allowed to create databases), create a database for wifiadmin, and
  then run the contents of mysql.sql to create the tables and initial data.

  For example:

  mysqladmin -u [user] -p create [database-name]
  mysql -u [user] -p [database-name] < mysql.sql

  Or you can use phpMyAdmin to do the same.

  In either case, you have to edit the config/config.php file and edit the
  following variables:

  $C_USERS_DBHOST = "localhost";       host where mysql is running
  $C_USERS_DB = "wifiadmin";           [database-name]
  $C_USERS_DBUSER = "wifiadmin";       [user]
  $C_USERS_DBPASS = "wifiadmin";       the password of [user]

3) Setup the registered routers. Wifiadmin has the capability to manage many (remote)
    routers. Of course you can still manage the server machine. We call this procedure
    "to register a router with the server". It may come handy when you try to have a
    "bare" router (with no resident services) and run your web server (where wifiadmin
    runs) on a different machine.

   Now assume that we have router.domain.com as remote router (R) and apache server with
    wifiadmin installed as server.otherdomain.com (S). Also "remoteuser" is the user that
    wifiadmin will connect to R and "apache_user" is the user name (e.g. www-data)  that
    apache runs as in S (see FIND APACHE USER section above). In order to work you need to
    perform the following :
  a)  At step 4 give sudo access to remoteuser at R (instead of apache_user at S)
  b)  Right now only ssh access is supported for remote routers. So set up your
      router R to accept connections from apahce_user@server.otherdomain.com as
      user remoteuser@router.domain.com without password. More on this at
      SSH_NOPASSWD supplied text file
  c)  Set up the ini routers file config/routers.ini. It should have the following format
    [router_name]
      url = router.domain.com
      username = remoteuser
      access_mode = ssh
      system_flavor = linux
      description = optional descriptive text

  SECURITY NOTICE: Having in mind the strength of ssh the security risks are the same
  as without ssh with the difference that they have to compomise your server S to gain
  sudo root access at router R but they can't break into the router directly.


4) Change your sudo configuration.
  Wifiadmin needs superuser access to *specific* executables. For the moment,
  this is done by giving superuser access to the user apache runs with on the local machine
  or remoter user on remote routers, using the sudo mechanism (need to have sudo installed).
  You can find out the user that apache runs with, by:

  ps aux | grep http   or   ps aux | grep apache

  You should use the visudo executable, or manually edit the file 'sudoers'.
  Add the following lines, replace www-data with the user apache runs with.

  # Cmnd alias specification
  Cmnd_Alias      WIFIADMIN = /sbin/iwconfig, /sbin/ifconfig, /sbin/iwlist,
  /sbin/iwpriv,  /sbin/route, /usr/bin/host, /usr/sbin/arp

  # User privilege specification
  www-data ALL=(ALL) NOPASSWD: WIFIADMIN

  Change the paths if iwconfig, ifconfig etc executables are located
  elsewhere in your system.

  *** You need to repeat the above procedure for every (remote) router ***

  SECURITY NOTICE:  This configuration, gives superuser priviledges for the specific commands
  to the user your  web server runs with at local or *remote* machines. This might have
  implications on system security. E.g. try to keep your web server and yout hole system secure.

5) OPTIONAL: If you want offline graphs to be created (network usage,AP users, Signal,etc)
  you can use the crontab -e command as the apache user and add the following line at
  the end of your crontab
*/4 * * * *  php /path/to/wifiadmin/create-update-rrds.php > /dev/null 2>&1

  or you can add the following by manually editing the systemwide /etc/crontab if for any
  reason you can not setup the apache user crontab (e.g. not permitted by your sysadmin)
*/4 * * * *  www-data php /path/to/wifiadmin/create-update-rrds.php > /dev/null 2>&1
  where we assume that apache runs as www-data user. (See FIND APACHE USER above)

  This creates(once) and updates the rrd databases.  RRD updates happen every 4 minutes.
  Change the value to suit your needs. Mind space characters from copy-pasting into your crontab!!

  Also make sure $C_gen_graphs is set to true (in config/config.php). In other case set to false.
  Default is disabled.

  Finally make sure the rrd_database and graphs directory as specified at the config/config.php
  are readable and writable by the webserver user.


6) Wifiadmin can send emails to confirm new user accounts, or remind user passwords.
  If $C_send_emails = true; in config.php file, wifiadmin will send emails.
  If you set $C_confirm_new_account = false; while $C_send_emails = true;, wifiamdin will
  send emails to remind passwords, but no email confirmation will be needed in order
  to set up an account.


7) Fire up your favorite browser, and point to
  'http://target-hostname/wifiadmin/'

  SECURITY NOTICE: WIFIADMIN HAS A DEFAULT ADMIN PASSWORD. Change the admin
  password as soon as possible, by logging in as user 'admin' with
  password 'wifiadmin'. Go to user management, choose 'admin', and
  type a different password. You can LOOSE complete network access
  to your box if you are careless enough...

7) Enjoy :)


